UpdateTranslationProgress

UpdateTranslationProgress
Header:	TranslationExtensions.h		Carbon status:	Unsupported

Allows your translation extension to update the progress dialog box that is displayed during file and scrap translation and give the user a chance to cancel.

OSErr UpdateTranslationProgress (
    TranslationRefNum refNum, 
    SInt16 percentDone, 
    Boolean *canceled
);

Parameter descriptions

refNum: A translation reference number. You should set this parameter to the translation reference number passed to your DoTranslateFileProcPtr or DoTranslateScrapProcPtr callback function. The Translation Manager uses that number internally.
percentDone: A value in the range 0–100 that indicates the percentage of the translation that has been completed (the approximate percentage of time elapsed until completion). When the translation is complete, you should call this function with this parameter set to 100 so that the user can see that the translation is complete.
canceled: On return, a pointer to a value which indicates whether or not the user canceled the translation. TRUE if the user clicked the Cancel button in the progress dialog box, or typed Command-period while the box is displayed; otherwise, FALSE. When TRUE, you should stop the translation, and your DoTranslateFile or DoTranslateScrap callback function should return the result code userCancelledErr.

function result: A result code.

DISCUSSION

Your translation extension should call this function only in response to the kTranslateTranslateFile or kTranslateTranslateScrap request code (that is, you should only call this function in your DoTranslateFile or DoTranslateScrap callback function). Do not call this function in response to any other request code or from any code that isn’t a translation extension.

You should already have called SetTranslationAdvertisement before calling UpdateTranslationProgress.

SPECIAL CONSIDERATIONS

This function might cause memory to be moved or purged; you should not call it at interrupt time.

AVAILABILITY

Not supported in Carbon. Available in Carbon 1.0 - 1.0.2 and later when running Mac OS 8.1 or later.

CARBON NOTES

The functions contained in TranslationExtensions.h were originally written to be used only by someone implementing a Mac Easy Open translation component. Carbon, however, is for applications and not extensions. Therefore, this function is not supported.

While this function was supported in versions of CarbonLib 1.0 to 1.0.2, this function will not be supported in later versions of Carbon.